home *** CD-ROM | disk | FTP | other *** search
/ LAUNCH 17 / LAUNCH.BIN / mac / Install These / NetSprocket 1.1 GM / NetSprocket Release Notes < prev    next >
Text File  |  1997-09-18  |  7KB  |  156 lines
  1. NetSprocket 1.1
  2. Release Notes
  3. ---------------
  4.  
  5. Please report all bugs to sprockets@adr.apple.com!
  6.  
  7.  
  8. What's New?
  9. -----------
  10.  
  11. NetSprocket 1.1 adds CFM-68K support, and has the following fixes and additions:
  12.  
  13. Ñ The NSpPlayerLeftMessage now includes a field for the name of the player who
  14.     left the game.  Previously, you only got the playerID, but since the player
  15.     was done there was no way to perform a GetInfo to get their name.
  16.     
  17.     CAVEAT I:  Be advised that this is a new feature to NetSprocket 1.1 and is
  18.     NOT backwards compatible with pre-1.1 builds.  If you use this field you must
  19.     make sure that your are using NetSprocket 1.1 or newer.  You can get the version
  20.     number with the NSpGetVersion() call.
  21.  
  22.     In short, make sure that everyone in the game is using 1.1 or newer if you
  23.     plan to use this field of the structure.
  24.  
  25. Ñ Bug that disallowed the creation of more than one game object at a time
  26.     has been fixed.  You are now only limited by other system resources,
  27.     such as memory or networking ports.  Keep in mind if you try to host
  28.     multiple games that you will get an error back if you try to host multiple
  29.     games with the same game name (for AppleTalk) or with the same port (for IP).
  30.     
  31. Ñ A significant problem was found under heavy flow (traffic) conditions
  32.     that could cause data to be delivered out of order.  This has been fixed.
  33.     
  34. Ñ If you specify an empty string (not a null string!) for the "type" parameter
  35.     to NSpDoModalJoinDialog, NetSprocket will use the game id (passed to 
  36.     NSpInitialize) to search for games on the AppleTalk network.  This matches
  37.     the default behavior for NSpGame_Host.
  38.     
  39. We have included a new test program that should provide a better example of
  40. how to effectively use NetSprocket.  The most important thing to note is how
  41. NetSprocket messages are handled both synchronously and asynchronously.  This
  42. method prevents problems where user actions, such as a mouse-down, could
  43. prevent the main event loop from calling NSpMessage_Get, and thereby cause
  44. a buffer overflow problem.
  45.  
  46. The number one problem we've seen with people using NetSprocket is apps running
  47. out of memory.  The reason this happens is that NetSprocket presents a 
  48. message API to the application.  If you have, say, a 50K message, NetSprocket
  49. doesn't hand that message to the client application until all 50K are received.
  50. This model makes NetSprocket much more suceptible to low memory problems that
  51. other, data-oriented, networking APIs.  There are three things you can
  52. do to minimize this kind of problem.
  53.     1.  Use small messages ( < 1K) as often as is practical
  54.     2.     Give NetSprocket as much memory as you can spare
  55.     3.    Use the async message hander
  56.     
  57. NetSprocket will still function if you don't do these things, but end user
  58. conditions will be much more likely to cause your app problems.
  59.  
  60. You should always check return values from NetSprocket functions.  Failure to
  61. do so is reckles, and will only cause you and your customers headaches.
  62.  
  63. What's coming?
  64. --------------
  65. Due to the significant changes that have taken place at Apple recently, we
  66. have been forced to cut back out engineering efforts in many areas, including
  67. NetSprocket.  The Win95 version will not be ready as planned, and we will
  68. be making changes only in modest increments.
  69.  
  70. NetSprocket (and the other Sprockets) are still supported, though, and we'll 
  71. continue making improvements as needed.  Please send bug reports or feature
  72. requests to sprockets@adr.apple.com
  73.  
  74.  
  75. Release Components
  76. ------------------
  77.  
  78. NetSprocket Release Notes                - this file
  79. NetSprocket.h                             - the header file to compile with.
  80. NetSprocketLib                           - release version of the library
  81. NetSprocketDebugLib                       - debugging version of the library
  82. NewNSpTest                               - test program
  83. NewNSpTest.╡                            - Code Warrior 11 project to build test
  84. NewNSpTest Sources                        - sources for test program
  85. NetSprocketLib68K                          - CFM-68K release version
  86. NetSprocketDebugLib68K                     - CFM-68K debugging version of the library
  87. NewNSpTest68K                              - new 68K test program
  88. NewNSpTest68K.╡                            - Code Warrior 11 project to build test
  89.  
  90. WARNING: don't place both the debugging and non-debugging versions of the
  91. library in the search path or you will not be sure which version you will be
  92. using.
  93.  
  94. Dependencies
  95. ------------
  96.  
  97. NetSprocket requires OpenTransport version 1.1.1 or later.
  98.  
  99. NetSprocket68K requires the CFM-68K 4.0 update, available from Apple
  100. Software Updates
  101.  
  102. NetSprocket requires the latest Universal Headers -- version 2.1.2 or later.
  103. You can find them on E.T.O. #20, the MacOS SDK CD-ROMs, Apple's web-site, or
  104. a number of other locations.
  105.  
  106.  
  107. Getting the Most out of NetSprocket
  108. -----------------------------------
  109.  
  110. To get the optimal performance out of NetSprocket, design your game to send
  111. "Normal" messages that contain less than 550 bytes of data.  This allows
  112. NetSprocket to use datagram-level delivery for both TCP/IP and AppleTalk. 
  113. Using "Registered" messages can cause a 2-50% network performance degradation,
  114. depending on a number of factors, including network bandwith, utilization,
  115. message size, and send frequency.
  116.  
  117. All messages, except ones sent from a player to himself, are sent through the
  118. host.  Therefore, the host is one "hop" from any other player, and two non-host
  119. players are always two "hops" apart.
  120.  
  121. Sending a message to a group is not as efficient as sending to everyone in the
  122. game, or to a single player.  It is usually more efficient than sending to each
  123. individual in the group separately.
  124.  
  125. You CAN NOT send messages at VBL (or any other interrupt) time with NetSprocket
  126. 1.0.  You should schedule a deferred system task, or just wait until system
  127. task time before sending.  You CAN however, call NSpMessage_Get at interrupt
  128. time.  We generally recommend against all interrupt-time calls to the Game
  129. Sprockets.
  130.  
  131. The number of players in a NetSprocket game is limited only by memory (and
  132. networking resources, such as available ports).  If you exepect to handle lots
  133. of players (14+), you need to make sure you give NetSprocket sufficient memory
  134. and queue elements when you initialize it.  If you get send failed or memory
  135. error message from NetSprocket, try giving it more memory.
  136.  
  137. If you have a situation where your game has players whose network throughput is
  138. greatly disparate, you need to make sure you don't choke the slow person.  For
  139. example, if you have 4 players on AppleTalk over Ethernet, and you have a fifth
  140. player join the game over a 28.8k PPP connection, and your fast machines are
  141. sending messages 30 times a second each, you're going to quickly gag the
  142. newcomer with too much data, and the host will simply not be able to deliver
  143. messages as quickly as you generate them.  The newcomer will be disconnected
  144. after approximately 20 messages have been queued up, waiting for flow control
  145. to lift before delivering them.  You can avoid this type of problem by
  146. throttling down your game's send rate to allow the newcomer to participate. 
  147. You can also avoid it by sending "Junk" messages instead of Normal.
  148.  
  149. NetSprocket 1.0 does not implement Round-Trip-Time or throughput functions.
  150.  You can implement your own RTT and thruput functions on top of
  151.  the NetSprocket API yourself, though.
  152.  
  153. Known Bugs
  154. ----------
  155.  
  156. Host renegotiation does not work.